Network & Performance Diagnostic Tool — README
=================================================
Version: 1.0.0
Date: 2025-09-09

OVERVIEW
--------
This is a browser-based diagnostic utility you can embed in WordPress or any static webpage. 
It measures basic connectivity (latency), a rough bandwidth estimate, shows memory usage (on supported browsers), 
offers simple cache/PWA clearing helpers, and includes a lightweight CPU stress test. No server-side code is required.

WHAT’S INCLUDED
---------------
- index.html  → The complete, self-contained tool (HTML/CSS/JS).
- README.txt  → This file.

REQUIREMENTS
------------
- Any modern browser (Chrome, Edge, Firefox, Safari).
  • Browser memory stats (performance.memory) are Chromium-only; other browsers will show “N/A”.
- HTTPS hosting recommended.
- Outbound access to:
  • https://www.google.com/generate_204  (latency probe)
  • https://httpbin.org/bytes/*          (bandwidth test payload)
  (You can change these endpoints in the script if your firewall blocks them.)

QUICK START
-----------
WordPress (Gutenberg):
1) Create or edit a Page.
2) Add a “Custom HTML” block.
3) Paste the full contents of index.html into the block and publish/update the page.
   • If you prefer, you can upload the HTML file to your theme/child-theme and enqueue it, but a Custom HTML block is fastest.

Static site:
1) Upload index.html to your web root or any directory.
2) Visit the URL (e.g., https://yourdomain.com/diagnostics/index.html).

CONFIGURATION
-------------
Inside index.html (the <script> section), you can adjust:
- Latency probe URL:
    const probe = 'https://www.google.com/generate_204';
  Change this if your network blocks Google. Any fast 204/200 endpoint with CORS tolerance works.

- Bandwidth endpoint and size:
    const url = 'https://httpbin.org/bytes/3000000?seed=' + Date.now();
  Increase or decrease the byte size (e.g., 5–10 MB) for more stable readings (longer test) or faster tests (smaller size).

- “Lite mode” app hints (localStorage):
    perf_mode = 'lite', data_range = '30d', max_indicators = '2'
  These are purely hints you can read in your own trading app if you want to integrate with its settings.

- PWA clearing:
  The buttons will unregister Service Workers and clear Cache Storage for the current origin. Some changes require a browser restart.

PRIVACY & DATA
--------------
- The tool does not collect or store personal data.
- Network tests perform outbound fetches (probe + bandwidth) from the user’s browser to public endpoints.
- Logs are kept in the page only; nothing is transmitted to your servers unless you modify the code to do so.

KNOWN LIMITATIONS
-----------------
- CPU usage is simulated (browsers do not expose actual CPU%).
- Browser HTTP cache cannot be fully purged via JavaScript; the tool clears Cache Storage + Local/Session Storage and prompts for a refresh.
- Corporate networks, strict firewalls, ad blockers, or privacy extensions may block the probe/bandwidth URLs, producing “Offline/Error” messages.
- Memory stats only appear in Chromium-based browsers (Chrome, Edge, Opera, Brave).

TROUBLESHOOTING
---------------
- Status shows “Offline”:
  Check if the probe URL is blocked. Replace with a reachable URL (e.g., your own origin: /wp-json/).

- Bandwidth test fails:
  Large payloads may be blocked or slow. Reduce the payload size (e.g., /bytes/1500000) or host a local test file over HTTPS.

- PWA data persists:
  Some browsers keep the SW state until a full restart. Close the app, quit the browser, and relaunch.

- Storage reset didn’t remove settings:
  Ensure you’re on the same domain/origin where settings were originally saved. Try using an incognito window for a fresh start.

CUSTOMIZATION
-------------
- Fonts & icons are loaded via Google Fonts (Inter) and Font Awesome 6 from CDNs. 
  You can self-host them for offline/air-gapped environments.
- Colors live in the <style> block; adjust to match your brand.
- All UI elements are namespaced under #diagnostic-tool to avoid theme collisions.

SECURITY NOTES
--------------
- Keep the tool on HTTPS.
- If you self-host the bandwidth file, make sure it is served with proper CORS and cache-busting (no-store) headers for accurate results.
- Avoid embedding untrusted third-party scripts on the same page.

CHANGELOG
---------
v1.0.0 — 2025-09-09
- Initial public release.

FAQ
---
Q: Should I distribute the tool as HTML or PDF?
A: HTML. The tool is interactive (JavaScript-based). A PDF would be non-interactive and unsuitable for diagnostics. 
   If desired, include a separate PDF “User Guide” for documentation, but keep the tool as HTML.

SUPPORT
-------
Questions or requests for customizations? Add a note in your page footer or contact your site admin/developer.
